home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Turnbull China Bikeride
/
Turnbull China Bikeride - Disc 2.iso
/
STUTTGART
/
PROBLEMS
/
EXTEDIT
/
Text%a0Only
/
EE-text
< prev
Wrap
Text File
|
1992-12-31
|
44KB
|
977 lines
The External Data Editing Protocol
Designed and Moderated by Jason Williams
Document version 1.02, 1 January 1993
(text version)
Introduction
============
The right idea
Those people who have used command-line UNIX a bit will have encountered a
very useful feature of it - when any program needs to edit a text document,
it simply saves that document to a temporary file, and invokes a text
editor on the file. When the text editor finishes, the application re-loads
the (changed) temporary file, and continues.
The wrong idea
Using Macromind Director and Hypercard on the Macintosh, I noticed that they
both include their own bitmap editor sections. These editors are both very
bad. SuperPaint 3 is very good, however: It would be nice if Superpaint
could be installed as the “bitmap editor section” of the other programs.
Superpaint could then be used as a shared bitmap-editor resource, and the
user gets a good bitmap editor (of their choice) for use within the other
programs.
This is the story of a new protocol for the Archimedes that allows us to do
something very similar to the UNIX-based idea mentioned above, only on the
desktop...
Using a separate data editor has distinct advantages-
• The main application doesn’t have to include all the editing code
(very useful, especially when multitasking several similar applications
alongside each other - the editor is a shared code resource)
• The editor code need only be resident in memory/executing while it is needed.
• The user can choose exactly the editor that they want to use and that one
is used globally.
• The main application can include support for data types of which it knows
relatively little, relying on the editor to provide that support.
The editor and even the layout of the data file format can therefore be
improved and augmented without having to update the main application.
• The ‘editor’ does not have to supply editing functions. It could, for
example, be a program that simply displays the data − allowing the user to
read some text, view or play a sound sample, or watch an ARMovie.
This is similar to hotlinking, but much simpler - the data is set out as a
single chunk, and some time later is brought back in as a single chunk.
The following are some examples of uses for the protocol − once you start to
think about it, more uses become apparent... in fact, you can do some
pretty impressive stuff with such a simple idea:
• A compiler that allows you to edit and re-compile a program from within a
text-editor window. This would augment the current “throwback” interface to
allow the compiler to actually open the text editor window on the
file-in-error, and automatically recompile the code when the user has
finished re-editing the file.
• A desktop publisher that “farms out” its draw-file illustrations to a
drawing package for editing. This can already be done, of course, but this
protocol would make the inter- application transfers 100% automatic.
Clicking an ‘edit’ option for a graphic in a DTP frame would bring up a
Draw-file editor window containing the graphic, and when the user is
finished editing, the graphic will be automatically updated to show the
changes.
(I personally feel that this is better than continuous hotlinking as it
allows the user to decide if and when they will actually replace the
DTP-frame data with the new, edited version − I guess a bit like an undo
feature).
• A drawfile editor that allows you to edit the text from text areas in a
normal text editor window. Notice how this could be combined with the last
point, so you could edit the text from a drawfile from a DTP doc. Imagine
selecting a text-area object in draw, and pressing ctrl-E and having an
edit window appear with the text in... or selecting a sprite, pressing
ctrl-E, and have a paint window containing the sprite appear.
• A Sound-Tracker song editor that displays (and possibly allows you to edit
and/or play) it’s instrument samples via a digitised sample editors
windows.
• An adventure authoring system that lets you edit descriptions in a
fully-blown text editor window, and edit pictures in a fully-blown sprite
or draw file editor window, while only having to provide the
location/object editing functions by itself.
• A hypermedia program could allow any type of file to be added into a
‘card’, and simply ask at runtime if there is any application present which
is able to ‘display’ the file: Unrecognised sound sample formats would be
picked up by another application and played, unrecognised data files
containing movies could be displayed, etc. without the hypermedia program
even knowing what the information in the data files was!
• A configuration/preferences application with a special configuration-file
format could be used to set all preference options for ALL running
applications that support this message system − Thus a central, consistent
configuration interface system is available, rather than each application
including code to supply preference options in its own (usually different)
interface style and method.
• “True colour” menus such as in paint and draw, for setting palette values
could be supplied by an editor: one that would allow users to use HSV or
CIE or RGB or CMYK or a rainbow-colour-picker, in order to mix the colour
that the client application wants − this would then be returned as (eg) an
RGB triplet for the client application to use.
Some of this can be achieved at present through the use of rather messy and
“hacky” trickery with Data Transfer messages and file-watching. However, a
proper protocol is very simple to implement, and yet exceedingly useful and
powerful, as I hope the above examples will have demonstrated to you.
To supply more integrated hotlinking than the above requires large
alterations and/or additions to the operating system and very complicated
protocols. However, the external editing protocol gives a very passable
base level of ‘hotlinking’ that is exceedingly quick and easy to support in
RISC OS applications, (relying mainly on existing data transfer protocols),
but which can increase the usability of the desktop for certain operations
immensely.
Overview of the protocol
========================
Two applications are involved in the process:
• An ‘editor’ (which supplies the display window and possibly also editing
functions),
• A ‘client’ (which initiates the edit, and supplies data to the editor
and/or expects data back from the editor later).
An application may include support for either/both editor and client ends of
the interface. The ‘user’ is the person using the computer.
From the client end:
The client application decides (usually at the request of the user) that
some data needs to be edited. Unable to supply this function itself, it
broadcasts to all other applications requesting an External Editing
session.
If no reply is recieved, then the client may take any appropriate action
(for example, run an editor supplied with the application and then
re-broadcast the request), but if the edit is not possible, the client will
inform the user with an error message indicating that the edit is not
possible.
If a reply is received, then a window will have been opened, and the user
may now edit the (blank) data in this window. The client now has the
following options:
• By starting a data transfer to the editor, the client can insert some data
at the ‘current position’ in the edited data; this can be done at any time,
but is mainly intended to supply an initial chunk of data to be edited.
(for example, a compiler might make Edit display a source code file if an
error has been found during compilation)
• By sending an appropriate message, the client can set a selection or
cursor position in the edited data. (for example, the compiler might
highlight the line of code containing the error)
• Another message may be sent by the client at any time to request that the
data be returned. (for example, the compiler could include a button/menu
option somewhere which says 'recompile', which will automatically retrieve
the code being edited and recompile it)
From the editor end:
Upon receipt of an external edit request broadcast, the editor checks the
data type, and if it is able to edit the data, it opens a suitable window
(on a 'blank' datafile) and replies to the message.
It will allow the user to edit the data (unless the request was for
read-only data, see below), and can also handle some extra functions:
• If a data transfer is started by the client, it will insert the new data
into the ExtEdit data, at the current 'cursor' position.
• If the client requests the data back, or if the user chooses the 'save'
menu option or closes the ExtEdit window, a reverse data transfer will be
initiated back to the client.
This is a very simple protocol at heart, and has been designed to be easy to
implement at the client end, though it takes a bit of work from the
editor's end in order to provide enough functionality.
=====================
Protocol message data
=====================
Before I detail the messages and protocol itself, I will explain some
‘global’ data fields that are contained in most messages. These data fields
always occur at the same position of messages and always have the same
meaning in messages, to enable quick and easy message turnaround and
general ease for programming.
Data type word (&eeee0ttt)
==========================
The least-significant 16 bits (0ttt) of this word contain a normal RISC OS
file type number.
The most significant 16 bits (eeee) contain an extension which augments the
file type number to provide more information on exactly what the data is.
This enables, for example, the text of an Impression document to be saved
with style information in DDF format to a text (&fff) file, but still be
differentiated from a normal text file, by using an extension.
A hypothetical extension might see the normal text file given the data type
word &00000fff, while then DDF text might be given the word &20150fff.
The extension &0000 is defined as conveying no extra information, i.e. it is
a ‘normal’ file of the specified type − the RISC OS file type alone conveys
all the necessary/available information.
Extensions &0001 through &04ff are reserved for ‘user’ use. However, it is
preferred that you request an official allocation anyway, for
future-proofing, to avoid clashes, and to enable all applications to share
one data type for each specific type of data, and thus improve the
effectiveness of the protocol.
If you have a type of data which can be differentiated to a more precise
level than RISC OS filetypes allow, then please write requesting an
extension number allocation. Allocations can also be requested for special
in-house data type numbers for conveyance of specially defined data chunks.
Job Handle (&eeeecccc)
======================
This is used in all communication between the client and editor as a
reference to a specific job. The client and editor both fill in their half
of this word with unique non-zero numbers, thus making a job handle which
is unique at both 'ends'. Once completed, the job handle for a session is
never changed. I suggest you use handles as follows:
• Each party simply ANDs off the 16 bits containing their own half of the
job handle. Thus, other than verifying its correctness, you need not
concern yourself with the other applications' half of the handle.
• Each application provides a handle value, so can use any handle value that
is easy for the programmer. Note however, that all handles should be unique
so that handles are not re-used. The suggested method for correctly
generating/using handles is:
Split your 16-bits of the job handle into 2 parts (perhaps a 10:6 bit
split?). The top 10 bits contain a unique (sequentially generated)
number, while the bottom 6 bits contain a reusable array index.
When a message for an existing session is recieved, mask the array-index
off the bottom to get quick-and-easy access to the relevant information.
Then check the entire 32 bits of the recieved handle against the copy
you have thoughtfully stored in your array of information on this session,
to ensure that it is a valid message. (and not, for example, an attempt
at communication from a previous (dead) session).
Message flags
=============
For the sake of simplicity, only one flagword definition has been made, and
this flagword is used in all the messages. Some flags are therefore invalid
in the context of some messages, and are simply ignored (if in doubt,
ignore the flag). This allows easy turnaround of messages, as most of the
messages are very similar in construction, allowing the programmer to make
minor alterations to a received message before using it as the contents of a
reply.
The flags should be set by the editor when replying to the client in order
to indicate the current status (e.g. if you are unable to supply read-only,
then clear the read-only bit; if you are unable to edit the data, then set
the read-only bit): If the client is not happy with the reported status,
they should report the problem to the user, and (possibly) abort the
session.
The defined flags are:
Bit Value Description
0 &1 Continue editing
Messages involving return of the data use this bit
to indicate whether the external edit session
should continue (bit = 1) or be abandoned (bit = 0)
once the data has been returned.
If the user closes the External Edit window, then
this flag will be ignored, as the user has
specifically indicated that they wish to end the
session.
1 &2 Selection only
The EditReturn message uses this bit to indicate
that the whole file (bit = 0) or the selection only
(bit = 1) should be returned. When returning data,
this bit indicates whether it is all/selection only
being returned.
2 &4 Read-only
This flag is used by the client to request that the
data be treated as read- only. If the editor
supports such a concept, it should not allow the
user to alter the data in any way. In case the
editor doesn't support this, the client should be
ready to ignore any attempt to return the data, even
though the editor should note the flag and not
return the data anyway.
3 &8 Immediate execution
Some data types can be 'played' or 'executed' (e.g.
sound samples/movies, script files). This flag is
used to request that execution of such data should
begin as soon as possible after receipt of the
message (this may involve waiting until all the
data has been transferred to the editor).
This can be used to make the 'editor' simply a
'playback device' that is called by other
multitasking applications.
This flag has no effect if the editor does not
support it; typically the case when the data type
doesn't allow for any concept of 'playback'.
4 &10 Adjust selection
When using the cursor-positioning message protocol,
this bit should be set if the selection range given
should replace the current selection (as if clicked
upon with select: bit = 0), or be added to the
current selection (as if clicked upon with adjust:
bit = 1).
This allows arbitrary selections to be built up for
files such as drawfiles, where the set of selected
items doesn't necessarily cover a single contiguous
range of values/objects.
5-31 - Reserved
Must be set to 0 on send, and ignored on recieve.
============
The Protocol
============
The protocol details and fine-print are explained later in this document.
However, to explain the basic interactions, as well as give a much clearer
indication of exactly what messages should be sent/received at any
particular time, I have drawn up some state diagrams. The protocol is based
around these 6 WIMP messages:
Message Name Description Number
Message_EditRq Request external editing session &45D80
Message_EditAck Acknowledge external edit &45D81
Message_EditReturn Request return of external edit data &45D82
Message_EditAbort Close editing session completely &45D83
Message_EditDataSave External edit equivalent of DataSave &45D84
Message_EditCursor Cursor/Selection placement &45D85
The messages that you can expect to send/receive at any point are shown in
the state diagrams (included as two drawfiles with this document)
"Client" Drawfile:
This shows all the states you should expect to encounter if you are a client
during a session. All of the states you should expect to encounter if you
are an editor during a session are detailed below:
"Editor" Drawfile:
The only part of the above protocol which is not described in this document
is the 'send data' process. This is initiated by the sending/receiving of
an EditDataSave message (which is in most ways identical to a normal
DataSave message), followed by normal RAM/disc inter- application data
transfers as detailed in Acorn's data-interchange message protocol.
The reason for doing this is to allow you to use existing code (very few
applications don't already have at least some support for inter-application
transfers) at the heart of this protocol, which saves effort and code
duplication. It would also be rather silly to define yet another protocol
if it isn't absolutely necessary.
============
The Messages
============
The messages used in the protocol are described in detail below:
---
Message_EditRq (Request external edit, number &45D80)
This is sent by a client as a broadcast.
Any editor recieving it should check the data type, and if they can supply
the service needed, they should claim the message with an EditAck, and open
a blank, appropriate editing window.
Notes
This message is always broadcast by the client and received by editors.
If your editor is read-only, it should only reply to this message if the
read-only flag is set. If a client would prefer to allow editing of the
data, it will broadcast with the read- only flag clear, but may re-broadcast
(if no reply is received) with the read-only flag set, in order to at least
display the information. This will stop read-only editors (displayers) from
grabbing data when fully-blown editors are available.
Definition
R0 = 19
R1 + 20 Data type word
R1 + 24 Job handle
The client should place a unique, non-zero integer job handle into
the least significant 16 bits of this word. The most significant
bits should all be set to zero. (i.e. 0x0000xxxx where xxxx is > 0)
R1 + 28 Flag word
Flags that are valid and should be supported are Continue-editing (0),
Readonly (2), Immediate execution (3).
Note that in the case of some data (sound samples),
Immediate-Playback implies that the data should not be displayed in
a window at all, but just played. If a display is needed as well as
playback, use the EditCursor message to initiate playback after
data transfer.
R1 + 32 Parent name
A 0-terminated string (max. length 20 characters including the
terminator) identifying the parent document/application (it’s file
leaf-name, generally).
On receipt, the editor should change the edit-window title to read
“(Parent) Filename” to indicate that the file is a temporary edit
of data from the document/application “parent”. If this entry is
blank (byte @ block+32 = 0) use the normal title-bar layout
"Filename", using just the leafname.
R1 + 52 Leaf name
A suggested leaf-name for the edited file. This will be displayed by
the editor in the titlebar of the edit-window, and will appear as
the default in the save-as box. If this entry is blank (byte @ R1 +
52 = 0) then use the default name for this filetype (e.g. Edit
would use “TextFile” for a text file)
This name can be up to 204 characters long (including terminator),
but it is preferred that it is less than 20 characters. If longer,
then it should appear like a normal RISC OS filename, i.e.
subdivided into short (preferably < 20 character) sections using a
period "." character. Only the 'leaf-name' of this (the last 20 or
fewer characters after the final period character) should ever be
expected to be used by the editor.
---
Message_EditAck (Acknowledge external edit, number &45D81)
This is sent by an editor in reply to an EditRq broadcast. If an editor can
supply the requested service it opens an appropriate editing window (on a
'blank' data file), and then replies to the client.
Notes
This is only sent by an editor in reply to an EditRq message.
The flag-word will be updated by the editor to reflect the current status.
e.g. the read- only flag will be set if 'editing' is in read-only mode, or
clear if not.
Definition
R0 = 17
R1 + 20 Data type word
Copied from EditRq message.
R1 + 24 Job handle
Partially copied from EditRq message.
The editor fills in the top 16 bits with a unique, non-zero integer
identifier, and the bottom 16 bits with the number given by the
client in the EditRq message.
R1 + 28 Flag word
Copied from EditRq message.
The editor should note these flags, and if it is unable to supply
any of the requested functions (e.g. read-only lock), it should set
these flags to indicate its current status.
If this status (e.g. editing is not possible − read only flag set)
is unacceptable to the client, it should warn the user, and then
abort the session (see below).
Valid flags are Continue-editing (0), Read-only (2),
Immediate-execution (3).
---
Message_EditReturn (Request return of external edit data, number &45D82)
This message is sent by the client to the editor, to request the return of
the data. This allows the client to provide a menu option or a button
somewhere that will retrieve the data or retrieve it and begin some
operation upon it.
Notes
This message is only sent by the client.
This is the only way in which a client can initiate return of the data, but
note that the editor can also initiate the transfer if the editing session
is closed by the user.
This should not be sent/should be ignored if 'editing' in read-only mode, as
the data should not have been changed!
Definition
R0 = 17
R1 + 20 Data type word
Included to allow the client to request the data back in a specific
format, not necessarily the original format.
If the editor cannot convert the data to this format for return,
then it should ignore the message, and the client must re-try with
a new data-type until a compromise can be attained! Note that as a
last ditch measure the type 'data' can be used, in which case it is
up to the client to recognise the format of the data from its
content. If no compromise can be attained, then abort the
operation, and assume that the editor is dead.
R1 + 24 Job handle
R1 + 28 Flag word
Valid flags are Continue-editing (0), Selection-only (1).
---
Message_EditAbort (Close editing session completely, number &45D83)
This message can be sent by either party. If this message is recieved, then
mark this job handle as defunct − From now on, any correspondence relating
to this job handle should be ignored.
Notes
The editor should close the window and stop editing.
Note that this should be done in all circumstances, even if the data has
been modified.
It is up to the client to warn the user and ensure that it’s OK to lose the
data. The client should always treat external data as modified data.
The sender of the message is responsible for any error report that may
indicate to the user that the edit has failed. Thus, the reciever should
not take any error-reporting action.
EditAbort should be sent whenever a job must be aborted (fatal error, task
quitting, etc.) in order to allow the other party to release workspace
allocated to the editing session. Remove the job handle from your records,
and ignore future references to it. Note that this means you should not
recycle job handle values.
Note, however, that in some fatal cases, it is better to not send an abort,
in order to allow the user to save their edited data and retrieve at least
some of the data which would otherwise be lost when your application
unexpectedly quits. This decision is thus left up to your judgement.
If playback of any type is running due to previous use of the
Immediate-Playback flag, then playback should cease immediately.
This message should not be sent before a session is correctly started (i.e.
when no valid job handle exists!), or during the course of any
inter-application daa transfers.
Definition
R0 = 17
R1 + 20 Reserved (should be 0).
R1 + 24 Job handle
---
Message_EditDataSave (Equivalent of DataSave, number &45D84)
This message is almost identical to Message_DataSave, and may be sent by
either party to initiate a data transfer (via the normal RAM or disc
transfer protocols). The message is used in exactly the same manner as
Message_DataSave, except instead of specifying a window/icon destination,
it supplies a job-handle to indicate the destination. Any followup messages
to an EditDataSave are normal Acorn Data transfer protocol messages.
All fields can/should be filled in as for a normal DataSave message, except
for the job handle field, which should instead be filled in wih the job
handle.
Notes
Data transfer, as for Message_DataSave, is from the sender of this message
to the reciever.
Normally, this message will follow EditRq, as soon as the client recieves
the EditAck, in order to supply the initial data for editing. However, it
should be noted that the message need not be sent if the client wants only
a ‘blank’ editing window.
This message may be sent more than once by the client, in which case each
data transfer will be inserted (if relevant, at the current 'cursor'
position, otherwise at the discretion of the author), into the ExtEdit
data.
If the editor cannot supply this service, either due to limited support for
this protocol, due to difficulties presented by the data type, or because
of the read-only flag setting, etc, the EditDataSave should be ignored and
an error should be reported, along the lines of “This operation is not
supported”.
This message is sent by the editor in reply to an EditReturn message, or
when it wishes to return the data. More discussion on return of data is
given below.
If the Immediate-Playback flag was set in the initial EditRq, and the data
is ‘playable’, then playback should be commenced as soon as this data
transfer is complete. As soon as playback finishes, the session should be
considered aborted (no extra messages need be sent).
The contents of the 'ignored' fields should be, um..., ignored. Their
contents are up to the discretion of the sender − if the author feels that
it is easier to call existing code that fills in these fields in some way,
they may contain some kind of valid data. However, the contents of these
fields should not be relied upon in any way − do not put extra 'personal'
data items in these words for use between your own programs!
Definition
R0 = 17
R1 + 20 Job handle (normally window handle)
R1 + 24 Ignored (normally icon handle)
R1 + 28 Ignored (normally X position)
R1 + 32 Ignored (normally Y position)
R1 + 36 Estimated size of data, in bytes
R1 + 40 File type of data
(Not data-type, just base file-type, as in normal DataSave message)
R1 + 44 Proposed leaf-name of file, 0-terminated.
---
Message_EditCursor (Set cursor/selection position, number &45D85)
This message can be used with some data types to set either a selection (a
range of data items which are selected) or a cursor position (a single data
item which is selected, or an insertion- point (caret) between data items
(e.g. characters)).
It is initially sent by the client to the editor to set new values, and is
immediately returned by the editor to indicate the success of the
operation.
Notes
A data unit is the smallest useful data item represented in a document.
Examples:
text files: units are characters
draw files: units are objects
sound samples and other binaries: units are bytes
Currently defined data units are listed below.
The cursor is some kind of ‘marker’ which can be placed at meaningful unit
positions within the document. It is always measured in terms of units from
the start of the data.
The cursor position is interpreted as follows:
The position given indicates a unit of data. The first unit of data is
given the unit number 1, the second is 2, etc. In the context of most
data (e.g. drawfiles), this unambiguously indicates a single unit.
Selections between two such unit positions are inclusive of those
positions.
In some cases (text files, etc), a caret is used to indicate the cursor
position, and is placed between two data units. In this case, the caret
is placed after the indicated unit.
A special-case resuts from these two definitions, which is placement of
the caret before the first data item, in which case a value of 0 should
be used. (In drawfiles and similar cases, a value of 0 should be treated
as a value of 1)
The selection is a group of units that can be described by a contiguous
range delimited by two cursor positions, called the start-of-selection and
end-of-selection. Arbitrary selections in data such as a drawfile can be
achieved using the 'Adjust-selection' flag in a series of EditCursor
messages.
Examples:
text files: The selection is a series of adjacent characters
draw files: Each selection can be any contiguous linear
sequence of objects
This is intended mainly for cursor positioning in text files. However, the
design should be sufficiently general to cater for most data types. If you
wish to support the protocol with an editor, then please contact me so that
we can sort out official details of the definition of units with that data
type. In all releases of this document, all official definitions at time of
release will be included below.
If in doubt, default to byte offsets.
Definition
R0 = 17
R1 + 20 Reserved (should be 0)
R1 + 24 Job handle
R1 + 28 Flag word
Valid flags are Read-only (2), Immediate-playback (3),
Adjust-selection (4).
The former two flags are used to attempt setting of new values for
the current state, and are returned to indicate the new status.
Immediate-playback can thus be used to halt or (re)start playback at
any time, if playback is multitasking.
R1 + 32 New cursor position *
R1 + 36 New start-of-selection position *
R1 + 40 New end-of-selection position *
R1 + 44 (reply only) Old cursor *
R1 + 48 (reply only) Old start-of-selection *
R1 + 52 (reply only) Old end-of-selection *
* Special cursor-position values
As mentioned above, positive unit offsets are used to set the cursor
position and start/end of the selection. However, in some cases you may not
wish to alter the current value of any of these settings, in which case,
you should fill the position field with the value -1 (&FFFFFFFF).
This allows you to set any or all of the positions individually. By setting
all three ‘new’ positions to -1, you may read the current values without
altering them.
Note that the flags will always be set to the new values given, so you can
also alter the flag settings only, by setting all ‘new’ positions to -1.
The special value -2 (&FFFFFFFE) should be used to indicate ‘end-of-data’.
Thus, to select the entire piece of ExtEdit data, you should set the
selection to the range ‘0’ to ‘-2’.
If the editor is unable to return a sensible value for the ‘old’ values
(e.g. there is no concept of a selection, or the selection can't be
represented as a single contiguous chunk), it will return values of -1 in
these fields. It should never return -2 (end-of-data), as the editor should
be capable of determining the correct end-of-data unit position.
Note also that in some situations (during movie/sound playback) the returned
cursor value may not be correct by the time you recieve the message. This
facility is really only useful for reading the position while paused, or
for less-often updated cursors such as the text cursor in Edit, and for
ensuring that a cursor-set operation worked. It would be preferable if this
message were not used on every NULL event to watch/control movie playback or
similar, except in exceptional (!) circumstances.
Current data unit definitions
Type Filetype Unit represents
Text fff character
Command ffe "
TaskObey fd7 "
TaskExec fd6 "
Obey feb "
Data ffd byte offset
BASIC ffb byte offset in tokenised data/
character offset in text form
Sprite ff9 sprite number/index
Palette fed colour number, as index into standard file format
DrawFile aff draw object
ARMovie ae7 animation frame number
==============
Sundry Details
==============
Return of data
==============
The ExtEdit data return can be initiated by:
Client:
Sends EditReturn message (usually prompted by a user action)
Editor:
Recieve EditReturn − return the data,
User clicks the ‘save’ option, the save-as OK button, or presses
RETURN in the save-as window − return the data, quit if the
continue flag is clear.
User drags the save-as file icon somewhere − save a copy of the data
to the indicated file, but don't take any other action − continue
editing as if nothing happened.
User clicks the window close icon − Ask with a dialogue box as for a
normal document being closed, offering Save/Discard/Cancel options
(If Save is clicked, return the data and quit, Discard means just
quit the session (send an abort), and Cancel will resume editing as
if nothing had happened)
Error handling
==============
If communications break down, you may assume that the session has been
aborted due to a bad implementation forgetting to inform you, or loss of
communications (the other application is confused or dead). However, be
careful about such assumptions: There are several places where no reply is
a perfectly valid response, and other places (EditCursor messages) where a
lack of response isn't necessarily a good indication of communication
breakdown. When in doubt, leave the session open until something definitive
happens to confirm the fact that communications have broken down.
Errors during file transfer should be treated as normal, but will sometimes
also indicate that the session has to be aborted − note that I have seen
several applications that spuriously report ‘reciever dead’ and other
similar errors in otherwise correct data transfers, which indicates that
somebody is failing to send a last ‘ack’ message, rather than an actual
break in communications... these should not necessarily spell doom for the
ExtEdit session!
In all cases when you think communications have broken down, or when you
must unexpectedly break the connection, you should do your best to send an
EditAbort (to ensure that the job has really been aborted) and abandon the
job tidily.
Closing a document containing ExtEdit data
==========================================
If you wish to quit or close a document containing data that is currently
tendered out for external editing, then the external data should be treated
as modified/unsaved data, i.e. you should inform the user “There is
unsaved (external) data in this document“, and allow them to initiate a
return-and-save of the data, or discard the data, much as you would with
normal unsaved data.
Please ensure that you send an abort in the latter case, as it is
undesirable to have unattached editing windows floating around.
Multi-file document handling
============================
Some packages (e.g. Impression) use a distributed document format (a
directory containing several files) which does not conform to ExtEdit’s
idea of a ‘single datafile’. In such cases, it is up to the designer of the
multi-file document to provide means for the document to be handled as a
single entity.
• With no extra effort, this can be achieved by never using RAMTransfers −
if a document is saved to disc, then the editor can detect the type and
treat it appropriately.
• In cases where RAMTransfer is desired, the designer of the data file
format must specify some means by which the data can be transferred as a
single “file”.
External edits of external edits!
=================================
A hypothetical case:
We have a DTP document containing a drawfile, and we ExtEdit the drawfile
out to Draw. From Draw, we ExtEdit out a sprite in the drawfile to Paint,
and a text-area to Edit.
When the data in the Drawfile needs to be returned (by user closing the draw
window or clicking save, or by an EditReturn message), what should Draw
do?
The External Edit protocol is designed to be a “Please edit this data and
tell me when it is complete“ system. Thus, no editor should attempt to
retrieve data that is being ExtEdit’d from within an ExtEdit document in
order to update the data it returns to its own client.
Draw should therefore treat its own copy of the drawfile as being complete
and disregard the ExtEdits from within it. Any Abort of this ExtEdit should
pass the Abort on to any 'child' ExtEdits.
However, if the editor-author is feeling particularly keen, you may treat
all external edit data as ‘modified’ data, and pop up an error box much
like that for closing an unsaved document: “There is unreturned external
data: Save/Discard/Cancel”. The user clicks one of the buttons:
Save
This should request the return of all ExtEdit data to update the drawfile,
and then return the drawfile back to the original client.
Discard
This should return the current data to the client, and send ABORT messages
to all related external editors.
Cancel
Editing continues as normal, giving the user the opportunity to (e.g.)
save the sprite from paint back into the drawfile, and discard the
modified edit docment (leaving the drawfile unchanged) before attempting
to close the drawfile again.
It is preferable that the user should not lose all external-edit data
without a warning. An ExtEdit data chunk should not be automatically
updated by sucking back ‘child’ ExtEdits, as this could result in
unintended ‘corruption’ of the document.
Alias$@EditType_xxx
===================
When requesting an External Edit session and receive no reply, first you
should re-try your request with different data-types and/or with the
read-only flag cleared in the hope of finding a suitable, though less ideal
editor for your data.
When no acceptable editor has been found by this method, you can attempt to
run a suitable editor from disc and then re-try your EditRq's (see below).
If all of this fails, then you should simply give up − report you inability
to the user, and suggest the type of editor you would like them to run
before attempting that operation again.
Running a suitable editor from disc
===================================
In this case, it is important that the user is able to configure in some way
which editor will be run. It is also important that any suitable editor
that is available can be run, rather than just one hard-wired editor that
the author expects to be available.
In order to improve this situation, I make the following suggestion which I
strongly urge you to follow: Editors should, in their !Boot file, set
variables along the lines of RunType, which indicates the editor to be run
for a particular RISC OS filetype, e.g. !Edit might use:
Set Alias $@RunType_FFF Run <Obey$Dir>.!Run %%*0
Set Alias$@EditType_FFF Run <Obey$Dir>.!Run
A client wishing to run an editor can then execute the command held in the
most appropriate Alias$@EditType_??? system variable, and then start
broadcasting EditRq messages again.
If no Alias$@EditType_??? variable is set, or if it fails for any reason to
successfully launch an editor (your retried EditRqs will fail), then you
should give up and report the problem to the user.
Current registered users of ExtEdit
===================================
The following applications already support the protocol:
StrongEd 2, StrongHlp
The following applications will soon support the protocol:
Zap, ZEdit, DSEdit II.
Requests For Allocations and Other Communications
=================================================
If you wish to use:
• flag bits
• data types
• messages or SWI support to augment the protocol
that are not defined in this document, then please request an official
allocation in order to ensure no clashes occur, and to allow others to
support any such new items as well. The power of this protocol comes from
unhindered sharing of it by as many applications as possible
Please write to the following address indicating the desired allocations,
the product for which they are to be used, and any details (extra protocol
conventions, data format, etc.) that will be needed for others who may wish
to support the allocated items.
If you wish to request allocations, or have any suggestions or queries to
put to me, then please do not hesitate to contact me:
Jason Williams,
R.D.2, Manuel Road,
Silverdale,
North Auckland,
New Zealand.
Post usually takes 1 week between NZ and Europe.
My email address will be changing in February/March 1993, but it is currently
jwil1@cs.aukuni.ac.nz